home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / mathlib.exe / MATHLIB.DOC < prev    next >
Encoding:
Text File  |  1991-11-30  |  17.8 KB  |  345 lines
  1.                    Math Libraries (MATHLIB) for Turbo Pascal
  2.                      Copyright (c) 1991, Waldman Sidelines
  3.        Harness the Power of the Advanced Coprocessors in Your Programs!
  4.                                        
  5.                                Waldman Sidelines
  6.                                 Cye H. Waldman
  7.                             Post Office Box 231157
  8.                            Encinitas, CA  92023-1157
  9.                     Tel: (619) 942-3016 : CSERVE 72245,1337
  10.                                        
  11.                                        
  12.                                  INTRODUCTION
  13.                                        
  14. MATHLIB offers Turbo Pascal users enhanced math function libraries specifically 
  15. written to tap the power of the 80287 and 80387 coprocessors.  All of the 
  16. intrinsic trigonometric and exponential functions plus nine additional ones 
  17. have been hand-coded in assembly language specifically for each coprocessor.  
  18. These nine additional functions were also coded in Pascal for use with any or 
  19. no coprocessor.  MATHLIB provides a consistent set of Turbo Pascal units for 
  20. use with any type of PC with improved performance for advanced coprocessors.
  21.  
  22. MATHLIB should be of particular interest to those performing numerically 
  23. intensive computations such as scientific and engineering calculations and 
  24. graphics applications which require coordinate transformations using 
  25. trigonometric relations.
  26.  
  27. This program is a shareware product.  You may distribute the original shareware 
  28. disk (not including the source code) to your friends for evaluation.  If you 
  29. use this program you are expected to register it with Waldman Sidelines.  
  30.  
  31. Your registration fee entitles you to use this software on a single computer 
  32. and to make as many copies of this software as you wish for your own backup 
  33. purposes.  Site licenses are available; call for details.  You may not use
  34. MATHLIB in a commercial product; a separate licence agreement must be 
  35. established with Waldman Sidelines.
  36.  
  37. Upon receipt of your registration you will receive a disk with the Pascal 
  38. source and the assembled object code required to compile the units, as well 
  39. as some bonus software (keep reading).  (Contact the author regarding 
  40. availability of the assembly language source code.) In addition, you will 
  41. receive notifications of future software updates.
  42.  
  43.                               LIMIT OF LIABILITY
  44.                                
  45. MATHLIB is distributed as-is. The author disclaims all warranties expressed or 
  46. implied.  The author will assume no liability for damages either from direct 
  47. use of this product or as a consequence of the use of this product.
  48.  
  49.                                    COPYRIGHT
  50.                                        
  51. MATHLIB is copyrighted with all rights reserved to Waldman Sidelines.
  52.                                        
  53.                                   TRADEMARKS
  54.  
  55. Turbo Pascal is a registered trademark of Borland International, Inc.
  56. 386MAX is a registered trademark of Qualitas, Inc.
  57. NetRoom is a trademark of Helix Software Company, Inc.
  58. Microsoft and MS-DOS are registered trademarks of Microsoft, Inc.
  59.  
  60. MATHLIB Documentation                                                   Page 1
  61.                                   DESCRIPTION
  62.  
  63. Three Turbo Pascal 6.0 units (TPU files) are provided with this software.  Two 
  64. of these provide faster floating point calculation by directly accessing the 
  65. advanced instruction set of the '287 and '387 coprocessors.  (These are not 
  66. accessible to math functions compiled under Turbo Pascal which is limited to 
  67. the 8087 instruction set.) The three units are MathLib (for use on any 
  68. machine, including those without a coprocessor), P287MathLib (for use only 
  69. with a '287 or better coprocessor) and P387MathLib (for use only with a '387 
  70. or better coprocessor).  These units are in files MATHLIB.TPU, P287MATH.TPU, 
  71. and P387MATH.TPU, respectively.  The units also contain a number of functions 
  72. which are not in the standard library.  These functions are coded in Pascal in 
  73. MathLib and in assembly language in P287MathLib and P387MathLib.  Units 
  74. P287MathLib and P387MathLib also contain assembly language replacements for 
  75. the intrinsic functions in the System Unit (i.e., ARCTAN, COS, EXP, LN, SIN).
  76.  
  77. These libraries are intended for users familiar with Turbo Pascal and the use 
  78. of units.  Those not familiar with units should refer to the Turbo Pascal 
  79. manuals.
  80.  
  81.                                 NOTES ON USAGE
  82.  
  83. 1.  Functions supported by all libraries (in alphabetical order):
  84.  
  85.     NOTE: The instrinsic transcendental functions from the Turbo Pascal System 
  86.     Unit (i.e., ARCTAN, COS, EXP, LN, SIN) can be of any type and are not
  87.     limited to type DOUBLE.  That would be the case in UNIT MathLib.
  88.     
  89.     FUNCTION ArcCOS(x: DOUBLE):DOUBLE;          { arc cosine function }
  90.  
  91.     FUNCTION ArcSIN(x: DOUBLE):DOUBLE;          { arc sine function }
  92.  
  93.     FUNCTION ARCTAN(x: DOUBLE):DOUBLE;          { arc tangent function }
  94.     
  95.     FUNCTION ArcTangent(x,y: DOUBLE):DOUBLE;    { optional arc tan function }
  96.     { returns arctan(y/x) in the proper quadrant, e.g., 0-360 degrees }
  97.     
  98.     FUNCTION COS(x:DOUBLE):DOUBLE;              { cosine function }
  99.     
  100.     FUNCTION EXP(x:DOUBLE):DOUBLE;              { exponential fn, e^x }
  101.     
  102.     FUNCTION Expo(x,y:DOUBLE):DOUBLE;           { exponential fn, x^y }
  103.     
  104.     FUNCTION LN(x:DOUBLE):DOUBLE;               { natural logarithm function }
  105.     
  106.     FUNCTION LOG(x:DOUBLE):DOUBLE;              { common logarithm function }
  107.     
  108.     FUNCTION SIN(x:DOUBLE):DOUBLE;              { sine function }
  109.     
  110.     PROCEDURE SINCOS(x:DOUBLE; VAR y,z:DOUBLE); { sine/cosine procedure }
  111.     { returns both sine and cosine; y = SIN(x), z = COS(x) }
  112.     
  113.     FUNCTION TAN(x:DOUBLE):DOUBLE;              { tangent function }
  114.     
  115.     FUNCTION Ten2TheX(x:DOUBLE):DOUBLE;         { exponential fn, 10^x }
  116.  
  117.     FUNCTION Two2TheX(x:DOUBLE):DOUBLE;         { exponential fn, 2^x }
  118.  
  119. MATHLIB Documentation                                                   Page 2
  120. 2.  Libraries are valid only for type DOUBLE.  (The author has found type
  121.     DOUBLE to be faster than type REAL.)
  122.  
  123. 3.  Libraries are compiled in Turbo Pascal 6.0 with the /v option.  Object
  124.     code is compiled with TASM 2.01 in the IDEAL mode with the TPASCAL MODEL.
  125.  
  126. 4.  Standard USES convention; e.g., USES MathLib or USES P287MathLib or
  127.     USES P387MathLib. (Can't mix 'n' match libraries; use one or the other.)
  128.  
  129. 5.  Install the three TPU files in a directory where Turbo Pascal will find
  130.     them and use them in the normal way.  E.g., can be USED in other units.
  131.  
  132. 6.  The advanced libraries (Px87MathLib) automatically supersede the intrinsic
  133.     math functions.  No explicit action is required on the part of the user.
  134.  
  135. 7.  Hardware-specific software can be developed by changing a single line of
  136.     code and recompiling.  E.g., USES MathLib ==> USES P387MathLib.
  137.  
  138. 8.  These libraries have been in use for about two years in mathematical
  139.     models of physical systems developed by the author.  Speed increases of
  140.     up to 40% have been observed in computationally intensive programs.
  141.  
  142. 9.  Until you become familiar with these programs it would be prudent to
  143.     verify that they give the results you expect by comparing output from the
  144.     same program compiled with the basic and advanced units.
  145.  
  146. 10. Registered users will receive a registration number and all Pascal source
  147.     code and assembled object code.  The source and object codes will allow 
  148.     compilation to past and future versions of Turbo Pascal without an 
  149.     assembler.  The registered version does not contain the initialization 
  150.     shareware information screen.  In addition, you will receive bonus 
  151.     software for the Wichmann-Hill random number generator (Byte, March 1987) 
  152.     in assembly and a solar/lunar ephemeris unit (both with source code).
  153.  
  154. 11. Technical support is available on CompuServe at ID 72245,1337.
  155.  
  156.                                 CUSTOM VERSIONS
  157.  
  158. Custom versions of the MATHLIB units can be developed for your organization.  
  159. For example, renaming the functions used in Px87MathLib so that the libraries 
  160. can be used concurrently, or addition of new functions hand coded in assembly 
  161. language.  Please contact Waldman Sidelines for a quotation.
  162.  
  163.                           PERFORMANCE CONSIDERATIONS
  164.     
  165. The table below shows time trials on a '486/33 (with 386MAX installed) with 
  166. the various libraries.  The numbers in the first three columns are the times 
  167. (in seconds) for 100,000 trials with randomly drawn arguments.  The numbers 
  168. are approximate because the time for drawing the random numbers is subtracted 
  169. out.  Nevertheless, as the ratios show, there is a substantial speed up with 
  170. the custom libraries.  Notice the very strong impact of using the intrinsic 
  171. TAN, SIN, and COS functions and SINCOS procedure in the 80387 coprocessor.  
  172. Also, good advantage is taken of the redefinition of the ARCTAN instruction in 
  173. the '387.  The libraries were tested extensively for accuracy; a program was 
  174. developed which drew random arguments and compared the results of the various 
  175. libraries.  Try the enclosed Savage benchmark (I find the '387 to be 2.4 times 
  176. faster) or make up your own.
  177.  
  178. MATHLIB Documentation                                                   Page 3
  179.                            Time for 100,000    Ratio     Ratio
  180.                            '087  '287  '387   287/087   387/087
  181.                            ----------------   -------   -------
  182.              LN:           2.21  1.22  1.21     1.83      1.83
  183.              LOG:          2.77  1.20  1.20     2.31      2.31
  184.              Two2TheX:     5.13  1.86  1.86     2.75      2.75
  185.              EXP:          2.88  1.89  1.89     1.53      1.53
  186.              Ten2TheX:     5.84  1.91  1.91     3.05      3.05
  187.              Expo:         5.47  2.82  2.82     1.94      1.94
  188.              TAN:          6.22  1.37  1.27     3.33      4.91
  189.              SIN:          2.87  2.33  1.27     1.24      2.26
  190.              COS:          2.87  2.40  1.27     1.25      2.26
  191.              SINCOS:       6.04  4.52  1.51     1.34      3.99
  192.              ARCTAN:       2.23  1.48  1.15     1.51      1.93
  193.              ArcTangent:   3.27  1.84  1.38     1.78      2.38
  194.              ARCSIN:       3.25  1.99  1.77     1.63      1.84
  195.              ARCCOS:       4.55  2.05  1.81     2.22      2.52
  196.                                 
  197.  
  198. In the course of developing the timing benchmarks it was discovered that the 
  199. presence of a memory manager had a rather significant effect on the 
  200. performance of the intrinsic math functions in Turbo Pascal.  The results with 
  201. a memory manager were about 25-40% slower.  We found this to be true for three 
  202. memory managers we tested (i.e., 386MAX, NetRoom, and Microsoft MS-DOS 5.0 
  203. HIMEM/EMM386).  We reported this anomalous behavior to Borland who were able 
  204. to duplicate this odd result with QEMM as well.  Also, there was a great deal 
  205. of variability in the results with the memory managers we tested.  In our 
  206. tests, 386MAX was the fastest and Microsoft MS-DOS 5.0 HIMEM/EMM386 was the 
  207. slowest.  The question arises as to whether the problem is with Turbo Pascal 
  208. or with the memory managers.  To answer that question we developed a similar 
  209. performance test of the intrinsic math functions in Microsoft FORTRAN.  The 
  210. memory manager (386MAX, in this case) only slowed down the operations by about 
  211. 2%, which is about what we would expect.  This seems to suggest some 
  212. deficiency in Turbo Pascal, but we have no hard core information as yet.  The 
  213. good news is that the mathematics functions in the advanced libraries provided 
  214. herein appear to be virtually unaffected by the memory mangers.  The table 
  215. below shows the comparisons.  Also look at the benchmarks reported in 
  216. SAVAGE.PAS.  Please share your own observations with us.
  217.         
  218.                            Time for 100,000   Time for 100,000
  219.                            Intrinsic Funcs.   P387MathLib Func.
  220.                            w/out 386MAX with  w/out 386MAX with
  221.                            -----------------  -----------------
  222.              LN:            1.57      2.21     1.19      1.21
  223.              LOG:           2.15      2.77     1.19      1.20
  224.              Two2TheX:      3.89      5.13     1.86      1.86
  225.              EXP:           2.26      2.88     1.89      1.89
  226.              Ten2TheX:      4.60      5.84     1.91      1.91
  227.              Expo:          4.23      5.47     2.81      2.82
  228.              TAN:           4.98      6.22     1.26      1.27
  229.              SIN:           2.25      2.87     1.27      1.27
  230.              COS:           2.25      2.87     1.27      1.27
  231.              SINCOS:        4.80      6.04     1.51      1.51
  232.              ARCTAN:        1.61      2.23     1.15      1.15
  233.              ArcTangent:    2.66      3.27     1.36      1.38
  234.              ARCSIN:        2.63      3.25     1.77      1.77
  235.              ARCCOS:        3.93      4.55     1.80      1.81
  236.  
  237. MATHLIB Documentation                                                   Page 4
  238.                 INVOICE & REGISTRATION FOR MATHLIB VERSION 1.0
  239.  
  240.         Please remit to:            Waldman Sidelines
  241.                                     Cye H. Waldman
  242.                                     P.O. Box 231157
  243.                                     Encinitas, CA  92023-1157
  244.  
  245.                               LIMIT OF LIABILITY
  246.  
  247.      The MATHLIB libraries (MathLib, Px87MathLib) are distributed as-is.
  248.      The author disclaims all warranties, expressed or implied.  The 
  249.      author will assume no liability for damages either from the direct 
  250.      use of this product or as a consequence of the use of this product.
  251.  
  252.      Please register one copy of MATHLIB for each user at your site.
  253.  
  254.         MATHLIB Registration     Qty. _____ @ $25.00 ea.     = ____________
  255.  
  256.         Calif. Residents Add 7.25% Sales Tax                 + ____________
  257.  
  258.                                                 Total Payment: ____________
  259.  
  260.      Registered users will receive a disk with the Pascal source code and 
  261.      assembled object code as well as bonus software consisting of a random 
  262.      number generator (assembly code) and ephemeris routines for solar and 
  263.      lunar zenith/azimuth (Pascal).  Registered users will be notified of new 
  264.      updates.  Suggestions for extensions of the libraries are welcome as 
  265.      well as requests for developments of similar libraries for other 
  266.      languages.  Comments are also welcome from those who elect not to 
  267.      register.  Thank you for using MATHLIB.
  268.         
  269.         Name:  ____________________________________________________________
  270.    
  271.         Company:  _________________________________________________________
  272.  
  273.         Address:  _________________________________________________________
  274.  
  275.         City, State, Zip:  ________________________________________________
  276.  
  277.         Day Phone:  _______________________  Eve:  ________________________
  278.  
  279.      
  280.      COMMENTS AND SUGGESTIONS
  281.  
  282.      ______________________________________________________________________
  283.  
  284.      ______________________________________________________________________
  285.  
  286.      ______________________________________________________________________
  287.  
  288.      ______________________________________________________________________
  289.  
  290.      ______________________________________________________________________
  291.  
  292.      ______________________________________________________________________
  293.  
  294.      ______________________________________________________________________
  295.  
  296.      ______________________________________________________________________
  297.          ----------------end-of-author's-documentation---------------
  298.  
  299.                          Software Library Information:
  300.  
  301.                     This disk copy provided as a service of
  302.  
  303.                            Public (software) Library
  304.  
  305.          We are not the authors of this program, nor are we associated
  306.          with the author in any way other than as a distributor of the
  307.          program in accordance with the author's terms of distribution.
  308.  
  309.          Please direct shareware payments and specific questions about
  310.          this program to the author of the program, whose name appears
  311.          elsewhere in  this documentation. If you have trouble getting
  312.          in touch with the author,  we will do whatever we can to help
  313.          you with your questions. All programs have been tested and do
  314.          run.  To report problems,  please use the form that is in the
  315.          file PROBLEM.DOC on many of our disks or in other written for-
  316.          mat with screen printouts, if possible.  PsL cannot debug pro-
  317.          programs over the telephone, though we can answer questions.
  318.  
  319.          Disks in the PsL are updated  monthly,  so if you did not get
  320.          this disk directly from the PsL, you should be aware that the
  321.          files in this set may no longer be the current versions. Also,
  322.          if you got this disk from another vendor and are having prob-
  323.          lems,  be aware that  some files may have become corrupted or
  324.          lost by that vendor. Get a current, working disk from PsL.
  325.  
  326.          For a copy of the latest monthly software library newsletter
  327.          and a list of the 3,000+ disks in the library, call or write
  328.  
  329.                            Public (software) Library
  330.                                P.O.Box 35705 - F
  331.                             Houston, TX 77235-5705
  332.  
  333.                                  Orders only:
  334.                                 1-800-2424-PSL
  335.                               MC/Visa/AmEx/Discover
  336.  
  337.                           Outside of U.S. or in Texas
  338.                           or for general information,
  339.                               Call 1-713-524-6394
  340.  
  341.                           PsL also has an outstanding
  342.                           catalog for the Macintosh.
  343.  
  344.  
  345.